home *** CD-ROM | disk | FTP | other *** search
/ Teach Yourself VRML 2 in 21 Days / Teach Yourself VRML 2 in 21 Days.iso / mac / ISO9660 / 3rdparty / POLYTRAN / dos / PT_DOS.ZIP / DOC_MAN / IMP_WAVE.MAN < prev    next >
Encoding:
Text File  |  1996-07-27  |  10.5 KB  |  261 lines
  1.  
  2.  
  3. Import-Wavefront()         Unix Programmer's Manual         Import-Wavefront()
  4.  
  5.  
  6. NAME
  7.      imp_wavefront - Wavefront .OBJ geometry import filter
  8.  
  9. SYNOPSIS
  10.  
  11.      This man page describes  the  options  specific  to  the  Wavefront  .OBJ
  12.      geometry import converter.
  13.  
  14. EXAMPLE CONVERSION SYNTAX
  15.  
  16.      To convert a Wavefront file to 3D Studio  using  the  default  parameters
  17.      listed in the setup.ini file:
  18.  
  19.           pt -i wave -o 3ds filename.obj
  20.  
  21.      To convert a Wavefront file to VRML and  override  some  of  the  default
  22.      options in setup.ini:
  23.  
  24.           pt -i wave -in-wave-print-stats = yes -o 3ds filename.obj
  25.  
  26. OVERVIEW
  27.  
  28.      This geometry import converter reads in Wavefront 'OBJ' format  files  in
  29.      their entirety, including vertex, normal and texture coordinates, as well
  30.      as grouping and smoothing  information.  Many  companies  which  sell  3D
  31.      models provide their datasets in the OBJ file format, so you can use this
  32.      converter to read in these data files and  be  guaranteed  nice  rendered
  33.      results.
  34.  
  35.      The converter will  also  read  material  definitions  from  a  Wavefront
  36.      material  file  (typically  which  has  a  file  extension '.mtl') if the
  37.      material file is referenced within the Wavefront geometry file (typically
  38.      which  has a file extension '.obj') using the 'mtllib' keyword. If one or
  39.      more Wavefront material files are listed on a single line then  all  will
  40.      be read into memory for possible reference by the geometry file.
  41.  
  42.      The converter first reads the entire file into memory; this includes  the
  43.      vertex,  normal  and  texture  coordinate  lists, their indice lists, all
  44.      group names, material names and texture names, and the  smoothing  groups
  45.      assigned to each polygon. Next, the converter computes new vertex normals
  46.      for polygons that don't  have  any  normals  and  that  have  a  non-zero
  47.      smoothing  group  assigned to them. If no smoothing groups are found then
  48.      the converter optionally creates smoothed vertex  normals  based  on  the
  49.      angle  between abutting polygon faces. As a last step, the polygonal data
  50.      is separated into separate objects based on a user-chosen criteria.
  51.  
  52. NOTES:
  53.  
  54.           If any texture map names are found in the file (ie: if  the  'usemap
  55.           <map_name>'  command  is  specified  in the file) and the '-in-wave-
  56.           surf-name-src' option of this converter  is  set  to  'use-mat-name'
  57.           then  texture  definitions  will  be automatically created for these
  58.           texture names and will be assigned to their corresponding  surfaces.
  59.           NOTE::  you  can  distinguish  these  textured  surfaces because the
  60.           texture map name is appended to the end of  the  surface  name  (the
  61.           surface and texture names are separated by three underscores '_').
  62.  
  63.  
  64.                                                                              1
  65.  
  66.  
  67.  
  68. Import-Wavefront()         Unix Programmer's Manual         Import-Wavefront()
  69.  
  70.  
  71.           If one or more group names are found on a 'g'  line  then  they  are
  72.           appended all together to form the group name used internally (ie: 'g
  73.           all airplane tail_fin').
  74.  
  75. COMMAND LINE OPTIONS
  76.  
  77.      The following options are specific to this import converter:
  78.  
  79.      -i wave
  80.           This is the optional command line option which  specifies  that  the
  81.           input  data  is  in the Wavefront .OBJ file format. If not specified
  82.           then the converter will try to guess the input  file's  format  from
  83.           its file extension (.obj) and then from the contents of its file.
  84.  
  85.      -in-wave-do-smoothing = [ yes | no ]
  86.           If set to 'yes'  then  new  vertex  normals  will  be  automatically
  87.           computed  for a polygon based on the smoothing group numbers located
  88.           within the .OBJ file.  Note: if explicit vertex normals are  already
  89.           associated  with  a  specific  polygon  then automatically generated
  90.           normals will not be computed for that polygon. Also  note  that  for
  91.           smoothing  to  take  place two or more polygons must be abutting and
  92.           share the same vertices.
  93.  
  94.      -in-wave-compute-avg-normals = [ yes | no ]
  95.           If set to 'yes' then new vertex  normals  will  be  computed  for  a
  96.           polygon  if it does not already have any vertex normals, and it does
  97.           not have a smoothing group  assigned  to  it  or  the  '-in-wave-do-
  98.           smoothing'  option  described  above  is  set  to 'no. The smoothing
  99.           criterion is based on the angle between abutting polygons;  smoothed
  100.           vertex  normals  will be computed if the angle between two polygons'
  101.           geometric surfaces normals is less than the angle specified with the
  102.           '-in-wave-smoothing-angle' option described below.
  103.  
  104.      -in-wave-smoothing-angle = #
  105.           This option sets the cut-off smoothing angle (in  degrees)  used  by
  106.           the  vertex  normal  computation algorithm. If the angle between two
  107.           abutting polygons is greater than this number then no smoothing will
  108.           occur  (a  crease  will  be  evident between the two polygons), else
  109.           smoothing will occur where the polygons meet. The default  angle  is
  110.           30 degrees.
  111.  
  112.      -in-wave-print-stats = [ yes | no ]
  113.           If set to 'yes' then statistics about  the  geometry  file  will  be
  114.           reported once it has been read in and processed.
  115.  
  116.      -in-wave-print-warn
  117.           If set to 'yes' then warning messages will be reported as  the  file
  118.           is read in. Warnings include unrecognized input and options, out-of-
  119.           range texture coordinates and out-of-range index values.
  120.  
  121.      -in-wave-surf-name-src = [ use-mat-else-group-name | use-mat-name |  use-
  122.           group-name | use-object-name ]
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                              2
  130.  
  131.  
  132.  
  133. Import-Wavefront()         Unix Programmer's Manual         Import-Wavefront()
  134.  
  135.  
  136.           This option specifies which method the converter is to use to assign
  137.           a  surface  definition  (a  material)  to  each  polygon.  Automatic
  138.           assignment of surfaces to the polygons will save you a lot  of  time
  139.           and headache.
  140.  
  141.           The 'use-mat-else-group-name' option uses the material name found in
  142.           the file as the new surface name, else it uses the group name as the
  143.           new surface name, else if uses the object name as  the  new  surface
  144.           name
  145.            if no material name is associated with the current  polygon(s).  If
  146.           no  material  or  group  name is assigned then the "default" surface
  147.           will be used. This option is the default.
  148.  
  149.           The 'use-mat-name' option uses the material name found in file, else
  150.           it uses the "default" surface if no material name is found.
  151.  
  152.           The 'use-group-name' option uses the group name found in  the  file,
  153.           else it uses the "default" surface if no group name is found.
  154.  
  155.           The 'use-object-name' option uses the object name found in the file,
  156.           else it uses the "default" surface if no object name is found.
  157.  
  158.      -in-wave-split-method = [ off | by-group-name | by-object-name |  by-mat-
  159.           name | by-txtr-name | by-smoothing-num ]
  160.  
  161.           This option selects which criterion is to be used when the polygonal
  162.           data  is  to be split up into different objects. If your 3D scene is
  163.           going to have many different objects in it then  it  is  recommended
  164.           that  the  OBJ  not be split up. However, if you want to modify each
  165.           individual part in the OBJ file then you will want to  split  it  up
  166.           into different objects.
  167.  
  168.           The 'off' option disables the OBJ file  from  being  split  up  into
  169.           separate objects.
  170.  
  171.           The  'by-group-name'  option  will  split  the  polygonal   geometry
  172.           according to the group name assigned to each polygon. It is the most
  173.           logical method for splitting the geometry since the group names  are
  174.           usually  assigned on an object-name basis by the person who designed
  175.           the 3D model. Groups are assigned to polygons in  the  OBJ  file  by
  176.           preceding   them   with   a   line   like:   'g   <group_name1>  ...
  177.           <group_nameN>'.
  178.  
  179.           The  'by-object-name'  option  will  split  the  polygonal  geometry
  180.           according  to  the  object name assigned to each polygon. Groups are
  181.           assigned to polygons in the OBJ file by preceding them with  a  line
  182.           like: 'o <object_name>'.
  183.  
  184.           The 'by-mat-name' option will split the polygonal geometry according
  185.           to  the  material name assigned to each polygon. You may want to use
  186.           this method if no group names are provided in  the  file  or  if  it
  187.           makes  more  sense to split by material name than by group name (for
  188.           example, the object might have 300 odd group names but 20  carefully
  189.           chosen  material  names).  Materials are assigned to polygons in the
  190.           OBJ  file  by   preceding   them   with   a   line   like:   'usemtl
  191.           <material_name>'.
  192.  
  193.  
  194.                                                                              3
  195.  
  196.  
  197.  
  198. Import-Wavefront()         Unix Programmer's Manual         Import-Wavefront()
  199.  
  200.  
  201.           The  'by-txtr-name'  option  will  split  the   polygonal   geometry
  202.           according  to the texture map name assigned to each polygon. In most
  203.           cases you will not use this method. Texture map names  are  assigned
  204.           to  polygons  in  the  OBJ  file by preceding them with a line like:
  205.           'usemap <texture_map_name>'.
  206.  
  207.           The 'by-smoothing-num' option  will  split  the  polygonal  geometry
  208.           according  to  the  smoothing group number assigned to each polygon.
  209.           Since smoothed polygons are usually clustered together as  one  sub-
  210.           object  this  method  can  be used to accurately extract sub-objects
  211.           from the polygonal data. However, it will probably create many  more
  212.           new  objects  than would the 'by-group-name' method above. Smoothing
  213.           groups are assigned to polygons in the OBJ file  by  preceding  them
  214.           with a line like: 's <smoothing_number>'.
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.                                                                              4
  260.  
  261.